Skip to main content

Using Cert manager

As part of our Managed Kubernetes Cluster offering, we provide a pre-installed Cert-Manager installation to simplify the process of obtaining and managing SSL/TLS certificates for your applications. This documentation will guide you through the usage of Cert-Manager and the pre-configured Let's Encrypt cluster issuers.

Prerequisites​

  • You have a Managed Kubernetes Cluster with Cert-Manager installed.
  • You have a basic understanding of Kubernetes and SSL/TLS certificates.

Overview of Cert-Manager​

Cert-Manager is a Kubernetes add-on that automates the management of SSL/TLS certificates. It provides a simple and efficient way to obtain, renew, and manage certificates for your applications.

Pre-configured Let's Encrypt Cluster Issuers​

We have pre-configured two Let's Encrypt cluster issuers for your convenience:

  • letsencrypt-prod: This issuer is used for production environments and will obtain certificates from the Let's Encrypt production API.
  • letsencrypt-staging: This issuer is used for testing and staging environments and will obtain certificates from the Let's Encrypt staging API.

Using Cert-Manager with Ingress Resources​

To use Cert-Manager with Ingress resources, you will need to create an Ingress resource that references a Certificate resource. The Certificate resource will define the desired certificate and the issuer to use. Here is an example of an Ingress resource that uses Cert-Manager to obtain a certificate:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-com
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-com
            port:
              number: 80
  tls:
  - hosts:
    - example.com
    secretName: example-com-tls

In this example, the Ingress resource is named example-com and will route traffic from example.com to the example-com service. The tls section of the Ingress resource references a secret named example-com-tls, which will be created by Cert-Manager. To obtain a certificate for the example-com domain, you will need to create a Certificate resource that references the letsencrypt-prod issuer:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
spec:
  secretName: example-com-tls
  issuerRef:
    name: letsencrypt-prod
  dnsNames:
  - example.com

In this example, the Certificate resource is named example-com and will obtain a certificate for the example.com domain using the letsencrypt-prod issuer. The obtained certificate will be stored in a secret named example-com-tls, which is also referenced by the Ingress resource.

Creating an Ingress Resource and Certificate​

To create an Ingress resource and Certificate, you can use the following commands:

kubectl apply -f example-com-ingress.yaml
kubectl apply -f example-com-certificate.yaml

Replace example-com-ingress.yaml and example-com-certificate.yaml with the names of your Ingress and Certificate resource files.

Annotations for Automated Certificate Management​

To automate the process of obtaining and renewing certificates, you can add the following annotations to your Ingress resource:

metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod

This will instruct Cert-Manager to automatically obtain and renew certificates for the domains specified in the Ingress resource. You can also add the following annotation to specify the DNS challenge solver:

metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    cert-manager.io/acme-challenge-type: dns-01

This will instruct Cert-Manager to use the DNS challenge solver to verify domain ownership. I hope this updated documentation helps your customers understand how to use Cert-Manager with Ingress resources! Let me know if you have any further requests.

Using Cert-Manager with Certificate resources​

To use Cert-Manager, you will need to create a Certificate resource in your Kubernetes cluster. The Certificate resource will define the desired certificate and the issuer to use. Here is an example Certificate resource that uses the letsencrypt-prod issuer:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
spec:
  secretName: example-com-tls
  issuerRef:
    name: letsencrypt-prod
  dnsNames:
  - example.com
  - www.example.com

In this example, the Certificate resource is named example-com and will obtain a certificate for the example.com and www.example.com domains using the letsencrypt-prod issuer. The obtained certificate will be stored in a secret named example-com-tls.

Troubleshooting​

Verifying the Certificate​

Once the Certificate resource is created, you can verify that the certificate has been obtained by checking the status of the Certificate resource:

kubectl describe certificate example-com

This will display the status of the Certificate resource, including the issuance date and the expiration date of the certificate.

Renewing Certificates​

Cert-Manager will automatically renew certificates before they expire. You can verify that the certificate is being renewed by checking the logs of the Cert-Manager pod:

kubectl logs -f cert-manager

This will display the logs of the Cert-Manager pod, including any renewal attempts.

Debug logs​

If you encounter any issues with Cert-Manager or the pre-configured Let's Encrypt cluster issuers, you can check the logs of the Cert-Manager pod for errors:

kubectl logs -f cert-manager

You can also check the status of the Certificate resource for any errors:

kubectl describe certificate example-com

If you need further assistance, please contact our support team.